/**
 ******************************************************************************
 * @file           : soft_timer.h
 * @brief          : Software Timer Header File
 ******************************************************************************
 * @attention
 *
 * 软件定时器
 * 基于系统滴答定时器实现
 * 支持单次和周期定时器
 *
 ******************************************************************************
 */

/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __SOFT_TIMER_H
#define __SOFT_TIMER_H

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/
#include <stdint.h>
#include <stdbool.h>

/* Exported types ------------------------------------------------------------*/

/**
 * @brief 定时器模式
 */
typedef enum
{
    TIMER_MODE_ONCE = 0,        /*!< 单次模式 */
    TIMER_MODE_PERIODIC,        /*!< 周期模式 */
} TimerMode_e;

/**
 * @brief 定时器状态
 */
typedef enum
{
    TIMER_STATE_STOPPED = 0,    /*!< 停止 */
    TIMER_STATE_RUNNING,        /*!< 运行中 */
    TIMER_STATE_EXPIRED,        /*!< 已超时 */
} TimerState_e;

/**
 * @brief 定时器回调函数类型
 */
typedef void (*TimerCallback_f)(void *arg);

/**
 * @brief 软件定时器结构体
 */
typedef struct
{
    uint32_t period;            /*!< 定时周期（ms） */
    uint32_t start_tick;        /*!< 起始滴答 */
    TimerMode_e mode;           /*!< 定时器模式 */
    TimerState_e state;         /*!< 定时器状态 */
    TimerCallback_f callback;   /*!< 回调函数 */
    void *callback_arg;         /*!< 回调参数 */
} SoftTimer_t;

/* Exported constants --------------------------------------------------------*/
/* Exported macro ------------------------------------------------------------*/
/* Exported variables --------------------------------------------------------*/
/* Exported functions --------------------------------------------------------*/

/* 初始化和配置 */
void soft_timer_init(SoftTimer_t *timer);
void soft_timer_config(SoftTimer_t *timer, uint32_t period_ms, TimerMode_e mode);
void soft_timer_set_callback(SoftTimer_t *timer, TimerCallback_f callback, void *arg);

/* 控制函数 */
void soft_timer_start(SoftTimer_t *timer);
void soft_timer_stop(SoftTimer_t *timer);
void soft_timer_restart(SoftTimer_t *timer);

/* 状态查询 */
bool soft_timer_is_running(SoftTimer_t *timer);
bool soft_timer_is_expired(SoftTimer_t *timer);
uint32_t soft_timer_remaining(SoftTimer_t *timer);
uint32_t soft_timer_elapsed(SoftTimer_t *timer);

/* 更新函数（需在主循环或定时器中断中调用） */
void soft_timer_update(SoftTimer_t *timer);

/* 延时函数 */
void soft_timer_delay_ms(uint32_t ms);

/* 系统滴答获取（需要用户实现） */
uint32_t soft_timer_get_tick(void);

#ifdef __cplusplus
}
#endif

#endif /* __SOFT_TIMER_H */
